---
title: 이미지
description: Astro에서 이미지를 사용하는 방법을 알아보세요.
i18nReady: true
---
import Since from '~/components/Since.astro';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import RecipeLinks from "~/components/RecipeLinks.astro";
import { Steps } from '@astrojs/starlight/components'
import ReadMore from '~/components/ReadMore.astro';

Astro는 프로젝트 내부에 로컬로 저장되거나, 외부 URL에서 연결되거나, CMS 또는 CDN에서 관리되는 등 사이트에서 이미지를 사용할 수 있는 여러 가지 방법을 제공합니다.

Astro는 이미지를 최적화하거나 변환하기 위해 내장된 [`<Image />`](#image-) 및 [`<Picture />`](#picture-) 컴포넌트, [Markdown 이미지 구문](#markdown-파일의-이미지) (`![]()`) 처리, [SVG 컴포넌트](#svg-컴포넌트), [이미지 생성 함수](#getimage를-사용하여-이미지-생성하기)를 제공합니다. 또한 기본적으로 [반응형 이미지의 크기를 자동으로 조정](#반응형-이미지-동작)하도록 구성하거나 개별 Image 및 Picutre 컴포넌트에 반응형 속성을 설정할 수 있습니다.

`.astro` 또는 Markdown 파일에서 기본 HTML 요소를 사용하거나, 파일 형식의 표준 방식 (예: MDX 및 JSX의 `<img />`)으로 이미지 및 SVG 파일을 사용할 수 있습니다. 하지만 Astro는 이러한 이미지에 대해 어떠한 처리나 최적화도 수행하지 않습니다.

또한 Astro에는 내장된 동영상 지원 기능이 없습니다. 동영상 콘텐츠 최적화 및 스트리밍 요구 사항을 처리하기 위해 [동영상 호스팅 서비스](/ko/guides/media/)를 선택할 것을 권장합니다.

<ReadMore>[`<Image />`](/ko/reference/modules/astro-assets/#image-) 및 [`<Picture />`](/ko/reference/modules/astro-assets/#picture-) 컴포넌트의 전체 API 참조를 확인하세요.</ReadMore>

## 이미지 저장 위치

### `src/` vs `public/`

Astro가 이미지를 변환, 최적화, 번들링할 수 있도록 가능하면 로컬 이미지를 `src/`에 보관하는 것이 좋습니다. `public/` 디렉터리의 파일은 처리 없이 항상 있는 그대로 빌드 폴더에 제공되거나 복사됩니다.

`src/`에 저장된 로컬 이미지는 `.astro`, `.md`, `.mdx`, `.mdoc` 및 기타 UI 프레임워크 등 프로젝트의 모든 파일에서 가져와 사용할 수 있습니다. 이미지는 콘텐츠 근처를 포함하여 모든 폴더에 저장할 수 있습니다.

이미지 처리를 피하려면 `public/` 폴더에 이미지를 저장하세요. 이러한 이미지는 프로젝트 파일에서 도메인의 URL 경로로 사용할 수 있으며 직접 공개 링크를 가질 수 있습니다. 예를 들어 사이트의 파비콘은 일반적으로 브라우저에서 식별할 수 있는 이 폴더의 루트에 배치됩니다.

### 원격 이미지

또한 [콘텐츠 관리 시스템 (CMS)](/ko/guides/cms/) 또는 [디지털 자산 관리 (DAM)](/ko/guides/media/) 플랫폼에 이미지를 원격으로 저장하도록 선택할 수도 있습니다.

Astro는 API를 사용하여 원격으로 데이터를 가져오거나 전체 URL 경로를 이용하여 이미지를 표시할 수 있습니다.

외부 소스를 다룰 때 추가적인 보호를 위해 Astro의 이미지 컴포넌트와 도우미 함수는 [구성에서 지정한 승인된 이미지 소스](#원격-이미지-승인)의 이미지만 처리 (예: 최적화, 변환)합니다. 다른 소스의 원격 이미지는 처리하지 않고 표시됩니다.

## `.astro` 파일의 이미지

<p>

**옵션:** `<Image />`, `<Picture />`, `<img>`, `<svg>`, SVG 컴포넌트
</p>

Astro의 템플릿 언어를 사용하면 [`<Image />`](/ko/reference/modules/astro-assets/#image-) 컴포넌트를 통해 최적화된 이미지를 렌더링할 수 있으며, [`<Picture />`](/ko/reference/modules/astro-assets/#picture-) 컴포넌트를 통해 여러 크기와 형식의 이미지를 생성할 수 있습니다. 두 컴포넌트 모두 컨테이너 크기에 따라 이미지의 크기를 조정하고 기기의 화면 크기와 해상도에 반응하는 [반응형 이미지 속성](#반응형-이미지-동작)을 허용합니다.

또한, `.astro` 컴포넌트에서 [SVG 파일을 Astro 컴포넌트로](#svg-컴포넌트) 가져와 사용할 수 있습니다.

`<img>` 및 `<svg>`를 포함한 모든 네이티브 HTML 태그는 `.astro` 컴포넌트에서 사용할 수 있습니다. [HTML 태그를 통해 렌더링된 이미지](#html의-img-태그를-사용하여-처리되지-않은-이미지-표시)는 처리되지 않은 상태 (예: 최적화, 변환 등) 그대로 빌드 폴더에 복사됩니다.

`.astro` 파일의 모든 **이미지의 `src` 속성의 값은 이미지 파일의 위치에 의해 결정됩니다**.

- 프로젝트 `src/` 폴더의 로컬 이미지는 파일의 상대 경로에서 가져오기를 사용합니다.

  Image 및 Picture 컴포넌트는 명명된 가져오기를 직접 사용하지만 (예: `src={rocket}`), `<img>` 태그는 가져오기의 `src` 객체 속성을 사용합니다. (예: `src={rocket.src}`)

- 원격 및 `public/` 이미지는 URL 경로를 사용합니다.

  원격 이미지의 경우, 전체 URL을 제공합니다. (예: `src="https://www.example.com/images/my-remote-image.jpg"`) 파일이 `public/` 폴더에 있는 경우, 파일의 위치에 해당하는 사이트의 상대 URL 경로를 제공합니다. (예: 이미지의 위치가 `public/images/my-public-image.jpg`인 경우, `src="/images/my-public-image.jpg"`)

```astro title="src/pages/blog/my-images.astro"
---
import { Image } from 'astro:assets';
import localBirdImage from '../../images/subfolder/localBirdImage.png';
---
<Image src={localBirdImage} alt="A bird sitting on a nest of eggs." />
<Image src="/images/bird-in-public-folder.jpg" alt="A bird." width="50" height="50" />
<Image src="https://example.com/remote-bird.jpg" alt="A bird." width="50" height="50" />

<img src={localBirdImage.src} alt="A bird sitting on a nest of eggs.">
<img src="/images/bird-in-public-folder.jpg" alt="A bird.">
<img src="https://example.com/remote-bird.jpg" alt="A bird.">
```

<ReadMore>[`<Image />`](/ko/reference/modules/astro-assets/#image-) 및 [`<Picture />`](/ko/reference/modules/astro-assets/#picture-) 컴포넌트의 필수 및 선택적 속성을 모두 포함한 전체 API 참조를 확인하세요.</ReadMore>

<RecipeLinks slugs={["ko/recipes/dynamically-importing-images" ]}/>

## Markdown 파일의 이미지

<p>

**옵션:** `![]()`, `<img>` (공개 및 원격 이미지)
</p>

`.md` 파일에 표준 Markdown `![alt](src)` 구문을 사용하세요. `src/`에 저장된 로컬 이미지와 원격 이미지는 처리 및 최적화됩니다. [전역 반응형 이미지를 구성](/ko/reference/configuration-reference/#imagelayout)하면 이러한 이미지도 [반응형 이미지](#반응형-이미지-동작)가 됩니다.

`public/` 폴더에 저장된 이미지는 최적화되지 않습니다.

```md
<!-- src/pages/post-1.md -->

# Markdown 페이지

<!-- src/assets/에 저장된 로컬 이미지 -->
<!-- 상대 파일 경로 또는 가져오기 별칭 사용 -->
![별이 빛나는 밤하늘](../assets/stars.png)

<!-- public/images/에 저장된 이미지 -->
<!-- public/의 상대 파일 경로 사용 -->
![별이 빛나는 밤하늘](/images/stars.png)

<!-- 다른 서버의 원격 이미지 -->
<!-- 이미지의 전체 URL 사용 -->
![Astro](https://example.com/images/remote-image.png)
```

HTML `<img>` 태그는 `public/`에 저장된 이미지 또는 원격 이미지를 최적화나 처리 없이 표시하는 데 사용할 수도 있습니다. 하지만 `<img>`는 `src`의 로컬 이미지를 지원하지 않습니다.

`<Image />` 및 `<Picture />` 컴포넌트는 `.md` 파일에서 사용할 수 없습니다. 이미지 속성을 보다 세밀하게 제어해야 하는 경우, [Astro의 MDX 통합](/ko/guides/integrations-guide/mdx/)을 사용하여 `.mdx` 파일 형식 지원을 추가하는 것을 권장합니다. MDX는 컴포넌트와 Markdown 구문의 결합과 [MDX의 이미지 옵션](#mdx-파일의-이미지)을 사용할 수 있도록 기능을 추가합니다.

## MDX 파일의 이미지

<p>

**옵션:** `<Image />`, `<Picture />`, `<img />`, `![]()`, SVG 컴포넌트
</p>

`.mdx` 파일에서 이미지와 Astro의 `<Image />` 및 `<Picture />` 컴포넌트를 모두 가져와 사용할 수 있습니다. [`.astro` 파일에서 사용하는 것](#astro-파일의-이미지)처럼 사용하면 됩니다. JSX의 `<img />` 태그는 처리되지 않은 이미지도 지원하며 [HTML의 `<img>` 태그와 동일한 이미지 가져오기를 사용](#html의-img-태그를-사용하여-처리되지-않은-이미지-표시)합니다.

또한, 가져오기가 필요없는 [표준 Markdown `![alt](src)` 구문](#markdown-파일의-이미지)도 지원합니다.

```mdx title="src/pages/post-1.mdx"
---
title: 페이지 제목
---
import { Image } from 'astro:assets';
import rocket from '../assets/rocket.png';

# MDX 페이지

// 동일한 폴더에 저장된 로컬 이미지
![야생의 휴스턴](houston.png)

// src/assets/에 저장된 로컬 이미지
<Image src={rocket} alt="우주에 떠 있는 로켓선" />
<img src={rocket.src} alt="우주에 떠 있는 로켓선" />
![우주에 떠 있는 로켓선](../assets/rocket.png)

// public/images/에 저장된 이미지
<Image src="/images/stars.png" alt="별이 빛나는 밤하늘" />
<img src="/images/stars.png" alt="별이 빛나는 밤하늘" />
![별이 빛나는 밤하늘](/images/stars.png)

// 다른 서버의 원격 이미지
<Image src="https://example.com/images/remote-image.png" />
<img src="https://example.com/images/remote-image.png" />
![Astro](https://example.com/images/remote-image.png)
```

<ReadMore>[`<Image />`](/ko/reference/modules/astro-assets/#image-) 및 [`<Picture />`](/ko/reference/modules/astro-assets/#picture-) 컴포넌트의 전체 API 참조를 확인하세요.</ReadMore>

## UI 프레임워크 컴포넌트의 이미지

<p>

**이미지 옵션:** 프레임워크 자체 이미지 구문 (예: JSX의 `<img />`, Svelte의 `<img>`)
</p>

`src`와 같은 이미지 속성에 접근하기 위해 [로컬 이미지를 먼저 가져와야 합니다.](#html의-img-태그를-사용하여-처리되지-않은-이미지-표시) 그러면 프레임워크의 자체 이미지 구문을 사용하여 이미지를 렌더링할 수 있습니다.

```jsx title="src/components/ReactImage.jsx"
import stars from "../assets/stars.png";

export default function ReactImage() {
  return (
    <img src={stars.src} alt="별이 빛나는 밤하늘" />
  )
}
```

```svelte title="src/components/SvelteImage.svelte"
<script>
  import stars from '../assets/stars.png';
</script>

<img src={stars.src} alt="별이 빛나는 밤하늘" />

```

[클라이언트 아일랜드는 프레임워크 자신의 유효한 코드를 포함해야 하므로](/ko/guides/framework-components/#프레임워크-컴포넌트에서-astro-컴포넌트를-사용할-수-있나요), UI 프레임워크 컴포넌트에서 Astro 컴포넌트 (예: `<Image />`, `<Picture />`, SVG 컴포넌트)를 사용할 수 없습니다.

하지만, 이러한 컴포넌트에서 생성된 정적 콘텐츠를 `.astro` 파일 내부에 있는 프레임워크 컴포넌트에 [자식으로](/ko/guides/framework-components/#프레임워크-컴포넌트에-자식-요소-전달) 전달하거나 [명명된 `<slot/>`](/ko/guides/framework-components/#프레임워크-컴포넌트에서-astro-컴포넌트를-사용할-수-있나요)을 사용하여 전달할 수 있습니다.

```astro title="src/components/ImageWrapper.astro"
---
import ReactComponent from './ReactComponent.jsx';
import { Image } from 'astro:assets';
import stars from '~/stars/docline.png';
---

<ReactComponent>
  <Image src={stars} alt="별이 빛나는 밤하늘" />
</ReactComponent>
```

## Astro 컴포넌트의 이미지

Astro는 이미지를 위한 두 가지 내장 컴포넌트 (`<Image />` 및 `<Picture />`)를 제공하며, SVG 파일을 가져와 Astro 컴포넌트로 사용할 수도 있습니다. 이러한 컴포넌트는 `.astro` 컴포넌트를 가져와 렌더링할 수 있는 모든 파일에서 사용할 수 있습니다.

### `<Image />`

기본으로 제공되는 `<Image />` Astro 컴포넌트를 사용하여 다음의 최적화된 버전을 표시합니다.

- `src/` 폴더에 있는 로컬 이미지
- 인증된 소스에서 가져오는 [구성된 원격 이미지](#원격-이미지-승인)

`<Image />`는 표시된 이미지를 제어하기 위해 로컬 또는 인증된 원격 이미지의 크기, 파일 유형 및 품질을 변환할 수 있습니다. 이 변환은 사전 렌더링된 페이지의 빌드 시 발생합니다. 페이지가 요청 시 렌더링될 때 이 변환은 페이지가 보여질 때 즉시 발생합니다. 결과 `<img>` 태그에는 `alt`, `loading` 및 `decoding` 속성이 포함되며 CLS (Cumulative Layout Shift)를 방지하기 위해 이미지 크기를 유추합니다.

:::note[Cumulative Layout Shift란 무엇입니까?]
[CLS (Cumulative Layout Shift)](https://web.dev/cls/)는 로드하는 동안 페이지에서 콘텐츠가 얼마나 이동했는지 측정하기 위한 Core Web Vital 지표입니다. `<Image />` 컴포넌트는 이미지에 대해 올바른 `width` 및 `height`를 자동으로 설정하여 CLS에 맞게 최적화합니다.
:::

```astro title="src/components/MyComponent.astro"
---
// 이미지 컴포넌트와 이미지 가져오기
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png'; // 1600x900의 이미지
---

<!-- 이미지 컴포넌트에서는 'alt'가 필수입니다. -->
<Image src={myImage} alt="이미지 설명" />
```

```html
<!-- 사전 렌더링된 출력 -->
<!-- 이미지가 최적화되었으며 적절한 속성이 적용되었습니다. -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="이미지 설명"
/>

<!-- 요청 시 렌더링되는 출력 -->
<!-- src는 요청 시 생성된 엔드포인트를 사용합니다. -->
<img
  src="/_image?href=%2F_astro%2Fmy_image.hash.webp&amp;w=1600&amp;h=900&amp;f=webp"
  <!-- ... -->
/>
```

`<Image />` 컴포넌트는 HTML `<img>` 태그가 허용하는 모든 속성뿐만 아니라 [여러 컴포넌트 속성](/ko/reference/modules/astro-assets/#image-속성)을 허용합니다.

다음 예시는 최종 `<img>` 요소에 적용될 이미지 컴포넌트에 `class`를 제공합니다.

```astro title="src/pages/index.astro" 'class="my-class"'
---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---

<!-- 이미지 컴포넌트에서는 'alt'가 필수입니다. -->
<Image src={myImage} alt="" class="my-class" />
```

```html 'class="my-class"'
<!-- 사전 렌더링된 출력 -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  class="my-class"
  alt=""
/>

```

:::tip
이미지가 최적화되거나 처리되지 않더라도 프로젝트에 특별히 구성되지 않은 `public/` 폴더의 이미지 또는 원격 이미지에 `<Image />` 컴포넌트를 사용할 수도 있습니다. 결과 이미지는 HTML `<img>`를 사용하는 것과 동일합니다.

그러나 모든 이미지에 이미지 컴포넌트를 사용하면 일관된 저작 환경을 제공하고 최적화되지 않은 이미지의 경우에도 누적 레이아웃 이동 (CLS)을 방지할 수 있습니다.
:::

### `<Picture />`

<p><Since v="3.3.0" /></p>

Astro의 내장 `<Picture />` 컴포넌트를 사용하여 이미지의 여러 형식 및/또는 크기가 포함된 `<picture>` 태그를 생성할 수 있습니다. 이를 통해 표시할 기본 파일 형식을 지정하면서, 대체 형식을 제공할 수 있습니다. [`<Image />` 컴포넌트](#image-)와 마찬가지로 미리 렌더링된 페이지에서는 이미지가 빌드 시 처리됩니다. 페이지가 요청 시 렌더링되는 경우에는 페이지가 표시될 때 즉시 처리됩니다.

다음은 `<Picture />` 컴포넌트를 사용하여 로컬 `.png` 파일을 웹 친화적인 `avif` 및 `webp` 형식과 필요 시 대체로 표시할 수 있는 `.png` `<img>`로 변환하는 예시입니다.

```astro title="src/pages/index.astro"
---
import { Picture } from 'astro:assets';
import myImage from '../assets/my_image.png'; // 1600x900의 이미지
---

<!-- Picture 컴포넌트에서는 'alt'가 필수입니다. -->
<Picture
  src={myImage}
  formats={['avif', 'webp']}
  alt="이미지 설명"
/>
```

```html
<!-- 사전 렌더링된 출력 -->
<picture>
  <source srcset="/_astro/my_image.hash.avif" type="image/avif" />
  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/my_image.hash.png"
    width="1600"
    height="900"
    decoding="async"
    loading="lazy"
    alt="이미지 설명"
  />
</picture>
```

<ReadMore>[`<Picture />` 컴포넌트의 속성](/ko/reference/modules/astro-assets/#picture-속성)에 대한 자세한 내용은 `astro:assets` 참조에서 알아보세요.</ReadMore>

### 반응형 이미지 동작

<p><Since v="5.10.0" /></p>

반응형 이미지는 다양한 기기에서 성능을 개선하기 위해 조정되는 이미지입니다. 이러한 이미지는 컨테이너에 맞게 크기가 조정될 수 있으며 방문자의 화면 크기와 해상도에 따라 다양한 크기로 제공될 수 있습니다.

`<Image />` 또는 `<Picture />` 컴포넌트에 [반응형 이미지 속성](/ko/reference/modules/astro-assets/#반응형-이미지-속성)을 적용하면 Astro는 이미지에 필요한 `srcset` 및 `sizes` 값을 생성하고 필요한 [스타일을 적용하여 이미지 크기가 올바르게 조정](#반응형-이미지-스타일)되도록 합니다.

이 반응형 동작이 [`image.layout`을 사용하여 전역적으로 구성](/ko/reference/configuration-reference/#imagelayout)되면 모든 이미지 컴포넌트와 [Markdown의 `![]()` 구문](/ko/guides/images/#markdown-파일의-이미지)을 사용하는 모든 로컬 및 원격 이미지에 적용됩니다.

`public/` 폴더에 있는 이미지는 최적화되지 않으며 반응형 이미지도 지원되지 않습니다.

:::note
하나의 반응형 이미지가 다양한 크기의 여러 이미지를 생성하여 브라우저에서 방문자에게 가장 적합한 이미지를 표시할 수 있도록 합니다.

미리 렌더링된 페이지의 경우, 빌드 시 이 작업이 실행됩니다. 특히 이미지 수가 많은 경우 프로젝트의 빌드 시간이 늘어날 수 있습니다.

요청 시 렌더링되는 페이지의 경우, 페이지가 방문될 때 필요에 따라 이미지가 생성됩니다. 이렇게 하면 빌드 시간에는 영향을 미치지 않지만 이미지가 표시될 때 수행되는 이미지 변환 횟수가 증가할 수 있습니다. 이미지 서비스에 따라 추가 비용이 발생할 수 있습니다.
:::

<ReadMore>[MDN 웹 문서에서 반응형 이미지](https://developer.mozilla.org/ko/docs/Web/HTML/Guides/Responsive_images)에 대해 자세히 알아보세요.</ReadMore>

#### 생성된 반응형 이미지 HTML 출력

레이아웃이 기본적으로 또는 개별 컴포넌트에 설정되면, 이미지의 크기와 레이아웃 유형에 따라 이미지에 `srcset` 및 `sizes` 속성이 자동으로 생성됩니다. `constrained` 및 `full-width` 레이아웃을 사용하는 이미지에는 컨테이너에 따라 크기를 조정하기 위한 스타일이 적용됩니다.

```astro title="src/components/MyComponent.astro"
---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image src={myImage} alt="이미지 설명" layout='constrained' width={800} height={600} />
```

이 `<Image />` 컴포넌트는 미리 렌더링된 페이지에 다음과 같은 HTML 출력을 생성합니다.

```html
<img
  src="/_astro/my_image.hash3.webp"
  srcset="/_astro/my_image.hash1.webp 640w,
      /_astro/my_image.hash2.webp 750w,
      /_astro/my_image.hash3.webp 800w,
      /_astro/my_image.hash4.webp 828w,
      /_astro/my_image.hash5.webp 1080w,
      /_astro/my_image.hash6.webp 1280w,
      /_astro/my_image.hash7.webp 1600w"
  alt="이미지 설명"
  sizes="(min-width: 800px) 800px, 100vw"
  loading="lazy"
  decoding="async"
  fetchpriority="auto"
  width="800"
  height="600"
  style="--fit: cover; --pos: center;"
  data-astro-image="constrained"
>
```

#### 반응형 이미지 스타일

[`image.responsiveStyles: true`](/ko/reference/configuration-reference/#imageresponsivestyles)를 설정하면 이미지 크기가 올바르게 조정되도록 몇 가지 전역 스타일을 적용합니다. 대부분의 경우 이 구성을 기본적으로 활성화하는게 좋습니다. 추가 스타일이 없으면 이미지가 반응형으로 동작하지 않습니다.

하지만 반응형 이미지 스타일을 직접 처리하고 싶거나, [Tailwind 4를 사용할 때 이러한 기본값을 재정의해야 하는 경우](#tailwind-4와-반응형-이미지)에는 기본값인 `false`를 유지하세요.

Astro에 적용되는 전역 스타일은 레이아웃 유형에 따라 달라지며, 생성된 `srcset` 및 `sizes` 속성에 가장 적합한 결과를 생성하도록 설계되었습니다. 기본 스타일은 다음과 같습니다.

```css title="Responsive Image Styles"
:where([data-astro-image]) {
	object-fit: var(--fit);
	object-position: var(--pos);
}
:where([data-astro-image='full-width']) {
	width: 100%;
}
:where([data-astro-image='constrained']) {
	max-width: 100%;
}
```

스타일은 [특이도](https://developer.mozilla.org/ko/docs/Web/CSS/CSS_cascade/Specificity)가 0인 [`:where()` 의사 클래스](https://developer.mozilla.org/en-US/docs/Web/CSS/:where)를 사용하므로 고유한 스타일로 쉽게 재정의할 수 있습니다. 모든 CSS 선택자는 `:where()`보다 특이도가 높으므로 이미지에 고유 스타일을 추가하여 스타일을 쉽게 재정의할 수 있습니다.

`<Image />` 또는 `<Picture />` 컴포넌트에서 `fit`과 `position` props를 설정하여 이미지별로 `object-fit` 및 `object-position` 스타일을 재정의할 수 있습니다.

#### Tailwind 4와 반응형 이미지

Tailwind 4는 Astro의 기본 반응형 스타일과 호환됩니다. 그러나 Tailwind는 [캐스케이드 레이어](https://developer.mozilla.org/ko/docs/Web/CSS/@layer)를 사용하므로 이 규칙은 항상 레이어를 사용하지 않는 규칙보다 특이성이 낮으며, 여기에는 Astro의 반응형 스타일도 포함됩니다. 따라서 Astro의 스타일링이 Tailwind 스타일링보다 우선합니다. Astro의 기본 스타일링 대신 Tailwind 규칙을 사용하려면 [Astro의 기본 반응형 스타일](/ko/reference/configuration-reference/#imageresponsivestyles)을 비활성화 하세요.

### SVG 컴포넌트
<p><Since v="5.7.0" /></p>

Astro를 사용하면 SVG 파일을 가져와서 Astro 컴포넌트처럼 사용할 수 있습니다. Astro는 SVG의 콘텐츠를 HTML 출력에 인라인으로 삽입합니다.

로컬 `.svg` 파일의 기본 가져오기를 참조하세요. 이 가져오기는 Astro 컴포넌트로 처리되므로, [동적 태그를 사용](/ko/reference/astro-syntax/#동적-태그)할 때와 동일한 규칙 (예: 대문자 사용)을 따라야 합니다.

```astro title="src/components/MyAstroComponent.astro"
---
import Logo from './path/to/svg/file.svg';
---

<Logo />
```

`<Image />` 또는 다른 Astro 컴포넌트와 마찬가지로 SVG 컴포넌트는 UI 프레임워크 컴포넌트에서는 사용할 수 없지만, `.astro` 컴포넌트에서 [프레임워크 컴포넌트로 전달](#ui-프레임워크-컴포넌트의-이미지)할 수 있습니다.

#### SVG 컴포넌트 속성

`width`, `height`, `fill`, `stroke`와 같은 props와 [기본 `<svg>` 요소](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/svg)에서 허용하는 다른 모든 속성을 전달할 수 있습니다. 이러한 속성은 자동으로 내부 `<svg>` 요소에 적용됩니다. 원본 `.svg` 파일에 속성이 있지만, 속성이 컴포넌트에 전달되면, 컴포넌트에 전달된 값이 원본 값을 덮어씁니다.


```astro title="src/components/MyAstroComponent.astro"
---
import Logo from '../assets/logo.svg';
---

<Logo width={64} height={64} fill="currentColor" />
```

#### `SvgComponent` 타입

<Since v="5.14.0" />

`SvgComponent` 타입을 사용하여 `.svg` 자산에 대한 타입 안전성을 강제로 적용할 수도 있습니다.

```astro title="src/components/Logo.astro"
---
import type { SvgComponent } from "astro/types";
import HomeIcon from './Home.svg'

interface Link {
	url: string
	text: string
	icon: SvgComponent
}

const links: Link[] = [
	{
		url: '/',
		text: 'Home',
		icon: HomeIcon
	}
]
---
```

### 사용자 정의 이미지 컴포넌트 만들기

`<Image />` 또는 `<Picture/>` 컴포넌트를 다른 Astro 컴포넌트로 래핑하여 재사용 가능한 사용자 정의 이미지 컴포넌트를 만들 수 있습니다. 이렇게 하면 기본 속성과 스타일을 한 번만 설정할 수 있습니다.

예를 들어, props로 속성을 받아 각 이미지에 일관된 스타일을 적용하는 블로그 게시물 이미지용 컴포넌트를 만들 수 있습니다.

```astro title="src/components/BlogPostImage.astro"
---
import { Image } from 'astro:assets';

const { src, ...attrs } = Astro.props;
---
<Image src={src} {...attrs} />

<style>
  img {
    margin-block: 2.5rem;
    border-radius: 0.75rem;
  }
</style>
```

## HTML의 `<img>` 태그를 사용하여 처리되지 않은 이미지 표시

[Astro 템플릿 구문](/ko/reference/astro-syntax/)은 최종 출력에 대한 완전한 제어를 위해 `<img>` 태그를 직접 작성하는 것도 지원합니다. 이러한 이미지는 처리 및 최적화되지 않습니다. 모든 HTML `<img>` 태그 속성을 허용하며, 필수 속성은 `src`뿐입니다. 그러나 [접근성을 위한 `alt` 속성](#대체-텍스트)을 포함할 것을 강력히 권장합니다.

### `src/`의 이미지

로컬 이미지는 기존 `.astro` 파일의 상대 경로에서 가져오거나 [가져오기 별칭](/ko/guides/imports/#별칭)을 구성하여 사용할 수 있습니다. 그런 다음 이미지의 `src` 및 기타 속성에 액세스하여 `<img>` 태그에 사용할 수 있습니다.

가져온 이미지 자산은 다음 시그니처와 일치합니다.

```ts
interface ImageMetadata {
  src: string;
  width: number;
  height: number;
  format: string;
}
```

다음 예시는 이미지 자체의 `height` 및 `width` 속성을 사용하여 누적 레이아웃 이동 (CLS)을 방지하고 핵심 웹 바이탈을 개선합니다.

```astro title="src/pages/posts/post-1.astro" "myDog.width" "myDog.height"
---
// 로컬 이미지 가져오기
import myDog from '../../images/pets/local-dog.jpg';
---
// 이미지 속성에 액세스
<img src={myDog.src} width={myDog.width} height={myDog.height} alt="짖고있는 개" />
```

### `public/`의 이미지

`public/`에 있는 이미지의 경우 `src` 값으로 이미지의 public 폴더에 상대적인 파일 경로를 사용합니다.

```astro '"/images/public-cat.jpg"'
<img src="/images/public-cat.jpg" alt="자고있는 고양이" >
```

### 원격 이미지

원격 이미지의 경우 이미지의 전체 URL을 `src` 값으로 사용하세요.

```astro '"https://example.com/remote-cat.jpg"'
<img src="https://example.com/remote-cat.jpg" alt="자고있는 고양이" >
```

### `<Image />` vs `<img>` 선택

`<Image />` 컴포넌트는 CLS를 방지하기 위해 이미지를 최적화하고 원본 가로 및 세로 비율을 기반으로 (처리할 수 있는 이미지의 경우) 너비와 높이를 추론합니다. 가능하면 `.astro` 파일에서 이미지를 사용하는 것이 좋습니다.

`<Image />` 컴포넌트를 사용할 수 없는 경우 HTML의 `<img>` 요소를 사용하세요. 예를 들면 다음과 같습니다.
  - 지원되지 않는 이미지 형식의 경우
  - Astro의 이미지 최적화를 원하지 않는 경우
  - 클라이언트 측에서 `src` 속성에 동적으로 접근하여 변경하는 경우

## CMS 또는 CDN의 이미지 사용

이미지 CDN은 [모든 Astro 이미지 옵션](#astro-파일의-이미지)에서 작동합니다. 이미지의 전체 URL을 `<Image />` 컴포넌트, `<img>` 태그 또는 Markdown 표기법에서 `src` 속성으로 사용하세요. 원격 이미지를 최적화하려면 [승인된 도메인 또는 URL 패턴을 구성](#원격-이미지-승인)하세요.

또는 CDN이 자체 SDK를 제공하여 Astro 프로젝트에 더 쉽게 통합할 수도 있습니다. 예를 들어, Cloudinary는 이미지를 `CldImage` 컴포넌트에 쉽게 넣을 수 있는 [Astro SDK](https://astro.cloudinary.dev/) 또는 Node.js 환경에서 `<img>` 태그와 함께 사용할 URL을 생성할 수 있는 [Node.js SDK](https://cloudinary.com/documentation/node_integration)를 지원합니다.

<ReadMore>[`<Image />`](/ko/reference/modules/astro-assets/#image-) 및 [`<Picture />`](/ko/reference/modules/astro-assets/#picture-) 컴포넌트의 전체 API 참조를 확인하세요.</ReadMore>

## 원격 이미지 승인

이미지 최적화를 위해 [`image.domains`](/ko/reference/configuration-reference/#imagedomains) 및 [`image.remotePatterns`](/ko/reference/configuration-reference/#imageremotepatterns)를 사용하여 승인된 이미지 소스 URL 도메인 및 패턴 목록을 구성할 수 있습니다. 이 구성은 외부 소스의 이미지를 표시할 때 사이트를 보호하기 위한 추가 안전 계층입니다.

다른 소스의 원격 이미지는 최적화되지 않지만 이러한 이미지에 `<Image />` 컴포넌트를 사용하면 CLS (Cumulative Layout Shift)를 방지할 수 있습니다.

예를 들어 다음 구성은 `astro.build`의 원격 이미지만 최적화할 수 있습니다.

```ts
// astro.config.mjs
export default defineConfig({
  image: {
    domains: ["astro.build"],
  }
});
```

다음 구성은 HTTPS 호스트의 원격 이미지만 허용합니다.

```ts
// astro.config.mjs
export default defineConfig({
  image: {
    remotePatterns: [{ protocol: "https" }],
  }
});
```

## 콘텐츠 컬렉션의 이미지

콘텐츠 컬렉션의 이미지는 사용 중인 파일 형식에 따라 [Markdown](#markdown-파일의-이미지) 및 [MDX](#mdx-파일의-이미지)에서와 동일한 방식으로 처리됩니다.

또한 현재 폴더에 대한 상대 경로를 사용하여 블로그 게시물의 표지 이미지와 같은 콘텐츠 컬렉션 항목 관련 이미지를 본문에 선언할 수 있습니다.

```md title="src/content/blog/my-post.md" {3}
---
title: "My first blog post"
cover: "./firstpostcover.jpeg" # "src/content/blog/firstblogcover.jpeg"로 해석됩니다.
coverAlt: "A photograph of a sunset behind a mountain range."
---

This is a blog post
```

콘텐츠 컬렉션 스키마의 `image` 도우미를 사용하면 이미지를 검증하고 가져올 수 있습니다.

```ts title="src/content.config.ts"
import { defineCollection, z } from "astro:content";

const blogCollection = defineCollection({
	schema: ({ image }) => z.object({
		title: z.string(),
		cover: image(),
		coverAlt: z.string(),
	}),
});

export const collections = {
	blog: blogCollection,
};
```

이미지를 가져와서 메타데이터로 변환하므로 이를 Astro 컴포넌트에 있는 `<Image/>`, `<img>`, `getImage()`에 `src`로 전달할 수 있습니다.

아래 예시는 이전 스키마에서 각 블로그 게시물의 표지 사진과 제목을 렌더링하는 블로그 인덱스 페이지를 보여줍니다.

```astro title="src/pages/blog.astro" {10}
---
import { Image } from "astro:assets";
import { getCollection } from "astro:content";
const allBlogPosts = await getCollection("blog");
---

{
	allBlogPosts.map((post) => (
		<div>
			<Image src={post.data.cover} alt={post.data.coverAlt} />
			<h2>
				<a href={"/blog/" + post.slug}>{post.data.title}</a>
			</h2>
		</div>
	))
}
```

## `getImage()`를 사용하여 이미지 생성하기

`getImage()` 함수는 HTML이 아닌 다른 곳 (예: [API 경로](/ko/guides/endpoints/#서버-엔드포인트-api-라우트))에서 사용할 이미지를 생성하기 위한 것입니다. 현재 `<Picture>` 및 `<Image>` 컴포넌트가 지원하지 않는 옵션이 필요한 경우, `getImage()` 함수를 사용하여 사용자 정의 `<Image />` 컴포넌트를 생성할 수 있습니다.

<ReadMore>[`getImage()` 참조](/ko/reference/modules/astro-assets/#getimage)에서 자세히 알아보세요.</ReadMore>

<RecipeLinks slugs={["ko/recipes/build-custom-img-component" ]}/>

## 대체 텍스트

모든 사용자가 동일한 방식으로 이미지를 볼 수 있는 것은 아니므로 이미지를 사용할 때 접근성은 특히 중요한 고려사항입니다. 이미지에 대한 [설명 대체 텍스트](https://www.w3.org/WAI/tutorials/images/)를 제공하려면 `alt` 속성을 사용하세요.

이 속성은 `<Image />` 및 `<Picture />` 컴포넌트 모두에 필요합니다. 대체 텍스트가 제공되지 않으면 `alt` 속성을 포함하라는 유용한 오류 메시지가 제공됩니다.

이미지가 단지 장식용인 경우 (즉, 페이지 이해에 도움이 되지 않는 경우) 화면 판독기가 이미지를 무시할 수 있도록 `alt=""`를 설정하세요.

## 기본 이미지 서비스

[Sharp](https://github.com/lovell/sharp)는 `astro:assets`에 사용되는 기본 이미지 서비스입니다. [`image.service`](/ko/reference/configuration-reference/#imageservice) 옵션을 사용하여 이미지 서비스를 추가로 구성할 수 있습니다.

:::note
`pnpm`과 같은 [엄격한 패키지 관리자](https://pnpm.io/pnpm-vs-npm#npms-flat-tree)를 사용하는 경우 Astro 종속성임에도 불구하고 Sharp를 프로젝트에 수동으로 설치해야 할 수 있습니다.

```bash
pnpm add sharp
```
:::

### 무작동 패스스루 서비스 구성

[어댑터](https://astro.build/integrations/?search=&categories%5B%5D=adapters)가 Astro의 내장 Sharp 이미지 최적화를 지원하지 않는 경우 (예: Deno, Cloudflare) `<Image />` 및 `<Picture />` 컴포넌트를 사용할 수 있도록 무작동 이미지 서비스를 구성할 수 있습니다. Astro는 이러한 환경에서 이미지 변환 및 처리를 수행하지 않습니다. 그러나 CLS (Cumulative Layout Shift) 없음, 강제된 `alt` 속성 및 일관된 작성 환경을 포함하여 `astro:assets` 사용의 다른 이점을 계속 누릴 수 있습니다.

Sharp의 이미지 처리를 방지하려면 `passthroughImageService()`를 구성하세요.

```js title="astro.config.mjs" ins={4-6} "passthroughImageService"
import { defineConfig, passthroughImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: passthroughImageService()
  }
});
```

## 자산 캐싱

Astro는 사이트 빌드 중에 로컬 이미지와 [승인된 소스의 원격 이미지](#원격-이미지-승인)에 대해 처리된 이미지 자산을 캐시 디렉터리에 저장합니다. 빌드 간에 캐시 디렉터리를 보존하면 처리된 자산이 재사용되어 빌드 시간과 대역폭 사용량이 개선됩니다.

기본 캐시 디렉터리는 `./node_modules/.astro`이지만, [`cacheDir`](/ko/reference/configuration-reference/#cachedir) 구성 설정을 사용하여 변경할 수 있습니다.

### 원격 이미지

자산 캐시의 원격 이미지는 [HTTP 캐싱](https://developer.mozilla.org/ko/docs/Web/HTTP/Caching)을 기반으로 관리되며, 원격 서버가 반환하는 [Cache-Control 헤더](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Cache-Control)를 준수합니다.
이미지는 Cache-Control 헤더가 허용하는 경우 캐시되며, [fresh](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching#fresh_and_stale_based_on_age)가 유지되는 동안 사용됩니다.

#### 재검증

<p><Since v="5.1.0" /></p>

[재검증](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching#validation)은 만료된 캐시 이미지가 여전히 최신 상태인지 원격 서버에 확인하여 대역폭 사용량과 빌드 시간을 줄입니다. 서버가 이미지를 여전히 신선하다고 표시하면 캐시된 버전이 재사용되고, 그렇지 않으면 이미지가 다시 다운로드됩니다.

재검증을 위해서는 원격 서버가 응답과 함께 [Last-Modified](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Last-Modified) 및/또는 [Etag (엔티티 태그)](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/ETag) 헤더를 전송해야 합니다. 이 기능은 [If-Modified-Since](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/If-Modified-Since)와 [If-None-Match](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/If-None-Match) 헤더를 지원하는 원격 서버에서 사용할 수 있습니다.

## 커뮤니티 통합

Astro 프로젝트의 이미지를 최적화하고 작업하기 위한 여러 타사 [커뮤니티 이미지 통합](https://astro.build/integrations?search=images)이 있습니다.
